home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / mus / midi / midiwatcher.lha / midiwatcher.doc < prev    next >
Text File  |  1993-02-12  |  8KB  |  161 lines
  1. ============================================================================
  2.  
  3.                         MidiWatcher v1.0 by Ed Mackey
  4.  
  5. ============================================================================
  6.  
  7. Yes folx, another one of my silly trinkets appears on the net ;-).
  8.  
  9. MidiWatcher is for people with MIDI keyboards.  It requires the midi.library
  10. v2 or higher by Bill Barton (not included).  It should run under almost any
  11. version of the Amiga's OS.
  12.  
  13. Basically, this program sits in the background and watches your MIDI IN port
  14. for certain tunes.  When it recognizes a tune, it runs a program.
  15.  
  16. For instance, if I need my directory utility up, I can do one of three
  17. things:  (1) I can search through subdirectories for its icon (takes too
  18. much time and is boring), (2) I can press a ToolManager hotkey (takes much
  19. less time but is still boring), or (3) I can reach over and play a little
  20. jingle on my MIDI keyboard, and up pops MegaD.  The third choice is clearly
  21. much more fun than either of the others ;-).
  22.  
  23. This program should be run from the CLI.  I suppose it would also run from
  24. Workbench if you did not need to pass any parameters to it.  Personally,
  25. I recommend putting it in your user-startup file.  If you type
  26. midiwatcher ?
  27. you will see:
  28.  
  29.     MidiWatcher by Ed Mackey.  Watch MIDI keyboard for tunes.
  30.     Usage: midiwatcher [-i source] [-f savefile] [-r] [-d]
  31.       -i selects a MidiIn source, defaults to MidiIn
  32.       -f selects a tune save file, defaults to S:midiwatch
  33.       -r turns on RECORD mode and adds a tune to file -f
  34.       -d turns on DEBUG mode (playback only) to see your tunes go.
  35.  
  36. Here is a more complete description of the options:
  37.  
  38. Well actually, -i is already described as much as it needs to be.  See the
  39. DOCs for midi.library to learn more about MIDI sources.  Note that ALL 16
  40. channels of your MIDI source will be monitored as if they were all one
  41. channel.  I realize this is somewhat uncool for some people, but remember
  42. this program is only a trinket.  You can also filter out MIDI channels with
  43. a midi.library patch bay type program.  Send me email if you want this
  44. changed.
  45.  
  46. -f selects a filename for the database of tunes to be recognized.  See -r
  47.  
  48. -d is DEBUG mode, so you can watch MidiWatcher trying to recognize tunes.
  49.  
  50. -r puts MidiWatcher in RECORD mode.  When in this mode, MidiWatcher saves
  51. every note it sees until you press CTRL-C.  It then writes to the savefile
  52. something that looks like this:
  53.  
  54.     # Your comments go here (such as name of tune)...
  55.     $3c 37 36 37 38 37 3b 3c 
  56.     @PLAY
  57.     *id midi_event
  58.     >echo "Tune recognized"
  59.  
  60. Only, you know, flush left because it is not in a DOC file.  :-)
  61. The save file will be appended to if it already exists, and created
  62. otherwise.  You should then edit this file with a text editor.  Here is
  63. what the lines mean:
  64.  
  65. # is a comment line.  Just write the name of the tune or whatever here.
  66.  
  67. $ has some hex numbers which you should not change.  These are the note
  68. numbers extracted from MIDI NoteOn messages during your recording.  Note
  69. there is no tempo or chord information here, just a sequence of NoteOns.
  70. I don't recommend playing chords unless you can start the individual
  71. notes of the chord in a certain order all the time.  I told you this
  72. program was a trinket, didn't I?
  73.  
  74. @ This is an optional line for people with ARexx.  It specifies an ARexx
  75. port, and as you know, ARexx port names are case-sensitive.
  76.  
  77. * This is an optional line for people with ARexx.  It contains a string
  78. to send as an ARexx message to the port named by the @ line.  Note that
  79. both the @ and * lines must be included for either to have an effect.
  80. People without ARexx should delete all @ and * lines.
  81. When a tune with an ARexx message is recognized, the message is prepared
  82. and sent.  MidiWatcher then continues normal processing _without_ waiting
  83. for the message to return.  However, if you send MidiWatcher a CTRL-C
  84. or a QUIT command (explained later), MidiWatcher will wait for all sent
  85. ARexx messages to return before quitting.
  86.  
  87. > This line specifies a CLI command to execute.  This line can be omitted
  88. only if both the @ and * lines are present and no CLI command is needed.
  89. Note that unlike ARexx messages, the CLI command will prevent MidiWatcher
  90. from running until the command's completion.  This should always be
  91. avoided like this:
  92. >run <NIL: >NIL: (your path & program name here)
  93. This use of the "run" command will make sure that MidiWatcher can keep
  94. multitasking with your newly-started program.
  95.  
  96. Note that if both an ARexx message and a CLI command are specified for
  97. a given tune, the ARexx message will be sent first, and the CLI command
  98. will be executed immediately after the message is sent.  As you can see
  99. from the example, I use this with Upd to play sound effects and launch
  100. programs at the same time, each time a tune is recognized.
  101.  
  102. ============================================================================
  103.  
  104.                            The ARexx Port
  105.  
  106. ============================================================================
  107.  
  108. Aha.  Not expecting that one were you?
  109.  
  110. Well, this program has an ARexx port of it's own, called MIDIWATCHER.
  111. It currently understands three commands, and these commands must
  112. always appear in UPPER CASE (sorry guys):
  113.  
  114.     SUSPEND    - Release the MidiIn (and hence the serial port, unless some
  115.                  other program is using MIDI), and just sit in the
  116.                  background until further notice.  Returning ARexx messages
  117.                  sent by tunes are still freed.  If MidiWatcher was already
  118.                  in suspend mode, this command is ignored.
  119.  
  120.     RESUME     - Leave SUSPEND mode if MidiWatcher was in it.  MIDI and your
  121.                  serial port are again tied up.
  122.  
  123.     QUIT       - Same as sending MidiWatcher's CLI process a CTRL-C.
  124.                  Deallocates MIDI, waits for any ARexx messages sent by
  125.                  tunes to come home, and exits (in that order ;-).
  126.                  Should work even in SUSPEND mode (I hope).
  127.  
  128. This ARexx port is of course not opened if you do not have ARexx (I know
  129. this sounds silly, but some programs let you use ARexx ports without
  130. having ARexx.  MidiWatcher is not one of these programs).
  131.  
  132. This port is also NOT available in RECORD [-r] mode (it's not needed then).
  133.  
  134. I suppose you could have a tune that caused MidiWatcher to send an ARexx
  135. message to itself.  This would not cause a problem (but of course a
  136. RESUME message would be useless, as MidiWatcher could not be in SUSPEND
  137. mode in the first place if it was sending messages).
  138.  
  139. NOTE:  If the serial port is not available to midi.library when
  140.        MidiWatcher is run or when MidiWatcher receives a RESUME
  141.        command, MidiWatcher will have a cow and act like you pushed
  142.        CTRL-C.  I suppose I should fix this.... nah....
  143.  
  144. Anyway, I added this ARexx port as an afterthought, so that I could have
  145. my terminal program use SUSPEND to grab the serial port and RESUME when
  146. it was done.
  147.  
  148. ============================================================================
  149.  
  150. Have fun with your new trinket.  Don't take this program too seriously,
  151. I only wrote it because I needed a short break from my senior project.
  152. I disclaim responsibility for any blah blah blah whatever.
  153. If you like this program send me money blah blah blah whatever.
  154.  
  155. Have fun!!
  156.                                      --Ed.
  157.  
  158.       Ed Mackey           BBS:  Somerton Telecomm II, (215) 464-6775
  159.       PO Box 475          IRC:  LineNoise
  160.       Wayne, PA 19087     Internet email:  elm4@lehigh.edu
  161.